PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/tools/rtmem.exe/RTMEM.DOC

Text File | 1992-03-10 | 16.6 KB | 403 lines

                                 RTMEM 1.10

    Purpose
    -------
    RTMEM (Run-Time MEMory) is a programmer's diagnostic aid that allows
    you to easily run programs with a specific amount of free memory
    available.  It is easier to use than the traditional "memory eaters"
    and more accurate than loading other programs, adjusting BUFFERS,
    etc., simply to take up space.

    Version 1.10 largely automates the process of determining the
    correct memory size when running programs under a debugger and adds
    options to specify the amount of EMS and XMS memory to make
    available.

    | marks features that are new or changed for this version.


    Background
    ----------
    It is not at all uncommon for a program to operate correctly on the
    developer's system but fail on a user's system.  There are many
    possible causes for this situation; one of these is that the user's
    system has less free memory available for the program.

    The traditional approach to analyzing whether or not this is the
    case is to reduce the developer's system's free memory in one way or
    another, then run the program to see if it fails.  This is typically
    accomplished by loading multiple copies of COMMAND.COM or DEBUG, by
    increasing FILES and/or BUFFERS, by running the program from the
    "shell" option of an application, or by using tools such as Turbo
    Power Software's EATMEM.

    The problem with adjusting BUFFERS or loading other programs before
    running the target is that it's hard to "eat" just the right amount
    of memory; and unless you have exactly the right amount of free RAM,
    you may not see the problem.  EATMEM is better, but it has two
    problems.  First, it's still rather coarse (allocations are made in
    units of K-bytes).  Second, it's a TSR.  Once memory has been
    "eaten" by EATMEM, you can't get it back without either rebooting or
    using a TSR manager such as MARK/RELEASE.

    RTMEM solves these problems; it allows you to specify the exact
    amount of free memory you want available to the target program, and
    it is not a TSR.  After running the target program, you still have
    all of your original DOS memory free.


    Use
    ---
    The complete syntax of RTMEM is:

  |     RTMEM [/Dxxxx] [/En] [/Xn] memorysize program [options]

    but basic usage of RTMEM is very simple:

        RTMEM memorysize d:\path\name.exe [options]

    The first argument is the amount of free memory you want available
    to the target program (NOT the amount of memory you want RTMEM to
    "eat").  It is specified in bytes, not KB or paragraphs.  Note,
    however, that DOS allocates memory in units of paragraphs (16
    bytes); RTMEM will round up to the next paragraph if you specify a
    number that is not a multiple of 16 bytes.  For ease of data entry,
    you can include commas in the memory size; RTMEM will ignore them.

    The second argument is the fully-qualified name of the program you
    want to run: the drive, path, name and extension.  You can omit the
    drive and/or path only if the program is located in the default
    drive and/or path; RTMEM does not search the system PATH.

    Following the program name are any parameters required for operation
    of the program (i.e., the same parameters/options you would use to
    run the program without RTMEM).

    Examples:

        RTMEM 314992 c:\arf\foo.exe /d /e

    This example runs C:\ARF\FOO.EXE with 314,992 bytes of free memory.
    The options "/d /e" are passed along to FOO.EXE.

        RTMEM 145,008 c:\dos\mem.exe

    This example runs MEM.EXE with 145,008 bytes of free memory.  The
    display from MEM.EXE shows the following when run on our system with
    this command:

        655360 bytes total conventional memory
        655360 bytes available to IBM DOS
        145008 largest executable program size      <---

    Before running the program, RTMEM displays the segment address at
    which the target program will load:

        Target program will load at 7F09

    This message indicates that the program will be loaded at segment
    7F09 (hex).  This will be the address of the program's PSP, not of
    its environment.

    When the target program terminates, RTMEM regains control and
    returns to DOS, releasing any memory that it has allocated.


  | Specifying free EMS
  | -------------------
  | To specify an amount of EMS (expanded memory) to make available, use
  | the /E option.  The /E takes a numeric argument, which is the amount
  | of free EMS (specified in K-bytes) that you want to make available
  | to the program.  For example, if you want FOO.EXE to run with 135008
  | bytes of DOS RAM and 512K of EMS:
  |
  |     RTMEM /E512 135008 C:\ARF\FOO.EXE
  |
  | The /E option, if present, must precede the DOS memory size.
  |
  | You can specify /E0 to "eat" all available EMS, leaving none for
  | the target program to use.
  |
  | Because EMS is always allocated in pages of 16K bytes each, RTMEM
  | rounds up to the next 16K if necessary.
  |
  |
  | Specifying free XMS
  | -------------------
  | To specify an amount of XMS (extended memory) to make available, use
  | the /X option.  The /X takes a numeric argument, which is the amount
  | of free XMS (specified in K-bytes) that you want to make available
  | to the program.  For example, if you want FOO.EXE to run with 135008
  | bytes of DOS RAM and 512K of EMS:
  |
  |     RTMEM /X512 135008 C:\ARF\FOO.EXE
  |
  | The /X option, if present, must precede the DOS memory size.
  |
  | This option affects only extended memory that is managed by an XMS
  | manager (like HIMEM.SYS, 386MAX and QEMM), not the so-called "INT
  | 15" extended memory that is used by programs like VDISK.
  |
  | This option affects only the size of the largest block of free XMS;
  | discontiguous smaller blocks are not affected.
  |
  | You can specify /X0 to "eat" all of the largest available block of
  | XMS.


    Environment
    -----------
    The question arises, "what about the system environment?"  Suppose
    a customer reports that your program fails on his system and the
    running MEM indicates 542,496 bytes of free memory.  You can easily
    run

        RTMEM 542,496 c:\myprog.exe

    But what if your DOS environment is not the same size as your
    customer's?  If your environment is 1K larger than his, doesn't that
    mean that using the same size will actually result in 1K less memory
    available to the program on your system than on his?

    In general, the answer is "no," if you are using either MEM or
    CHKDSK to report free memory.  Both of these programs report the
    amount of memory that will be available to run a program AFTER space
    has been allocated for the current environment.  RTMEM also follows
    this convention; in other words, if you tell it to allow X bytes of
    free memory for a program, it assumes you mean X bytes of memory
    free AFTER the new environment has been allocated.  Therefore, use
    the exact number reported by either MEM or CHKDSK when running
    RTMEM.


    Running under a debugger
    ------------------------

  | Once you have determined that memory size is indeed the problem, you
  | may need to run the target program (with the correct memory size)
  | under a debugger.  The debugger must be run under RTMEM in such a
  | way that the correct amount of memory is available to the target
  | program when it has been loaded by the debugger.
  |
  | In other words, the trick is to run the debugger in the correct
  | amount of memory (using RTMEM) so that, after the memory used by the
  | debugger has been subtracted, the correct amount is left for the
  | target program.
  |
  | Here is how to set the correct amount of memory when running under
  | a debugger:
  |
  |     1. Load the target program under your debugger; do not begin
  |     execution.  Display the CPU registers and make a note of the
  |     value contained in the DS register.  This is the segment address
  |     at which your debugger has loaded the target program.  NOTE:
  |     use the full path to your debugger when you run it; this is
  |     necessary to ensure that the debugger's environment is the same
  |     size it will be when you run it under RTMEM later.
  |
  |     2. Exit the debugger back to the DOS prompt.
  |
  |     3. Now run the debugger under RTMEM, adding a /D option before
  |     the memory size. The argument of the /D option is the segment
  |     address noted in step 1:
  |
  |         RTMEM /Dxxxx memorysize debugger program [options]
  |
  | For example, suppose you want to run C:\ARF\FOO.EXE under DEBUG with
  | 135,008 bytes of free memory.  The steps above might look like this:
  |
  |     1. Run DEBUG:
  |
  |             C:\DOS\DEBUG.COM C:\ARF\FOO.EXE
  |
  |        Display the registers:
  |
  |             AX=0000  BX=0000  ...
  |             DS=0BCB  ES=0BCB  ...
  |
  |        Note the DS value (0BCB).
  |
  |     2. Quit DEBUG.
  |
  |     3. Start DEBUG again, this time using RTMEM; use the /D option,
  |     specifying the segment address from step 1:
  |
  |         RTMEM /D0BCB 135008 C:\DOS\DEBUG.COM C:\ARF\FOO.EXE
  |
  | To confirm, note the initial value of DS when the target program is
  | loaded under your debugger.  This should be the same value displayed
  | by RTMEM if you run the target program directly (without the
  | debugger) and specify the desired memory size.  In our example:
  |
  |     C> RTMEM 135008 C:\ARF\FOO.EXE
  |     target program will load at 7F09
  |     ...
  |     C> RTMEM /D0BCB 135008 C:\DOS\DEBUG.COM C:\ARF\FOO.EXE
  |     -R
  |     AX=0000  BX=0000  ...
  |     DS=7F09  ES=7F09  ...
  |
  | Note that the value of DEBUG's DS is the same as the load address
  | displayed by RTMEM.


    Error messages
    --------------
    RTMEM reports the following errors:

    requested size greater than available memory
        The memory size you specified on the command line is greater
        than the amount of memory currently available.  RTMEM can only
        decrease free memory, not increase it.

    program not found (remember to use path and extension)
        RTMEM was unable to find the target program.  Be sure that you
        have specified everything it needs to find the program: the
        drive (if the program is not on the current drive), the
        directory (if the program is not in the current directory), and
        the program name AND extension.  Do not rely on the PATH.

    requested size is not enough to run the program
        RTMEM could not run the target program due to insufficient
        memory; in other words, you executed "RTMEM 50000 foo.exe",
        and FOO.EXE cannot run in 50,000 bytes of memory.

    error running program
        Catch-all message for other errors encountered in attempting
        to run the program.  You should not see this message...

    memory size specified greater than 1MB
        Just what it says: you specified a memory size larger than 1MB.

    EMS manager not found
        RTMEM was unable to locate the EMS manager software.  Either the
        driver is not loaded or it has been corrupted.

    EMS manager not responding
        The EMS manager software is not responding correctly; it may
        be corrupted.

    requested EMS greater than available
        The amount of free EMS memory your requested with the /E option
        is greater than the amount of EMS currently available.

    XMS manager not found
        RTMEM was unable to locate the XMS manager software.  Either the
        driver is not loaded or the system has been corrupted.

    XMS manager not responding
        The XMS manager software is not responding correctly; it may
        be corrupted.

    requested XMS greater than available
        The amount of free XMS memory your requested with the /X option
        is greater than the amount of XMS currently available.


    Version history
    ---------------
    1.10 (10 Mar 92)
        Adds /D option (set size under debugger)
        Adds /E option (specify available EMS)
        Adds /X option (specify available XMS)

    1.10 (1 Jan 92)
        Initial release


                         COPYRIGHT/LICENSE/WARRANTY
                         --------------------------

    This document and the program file RTMEM.COM ("the software") are

                             Copyright (C) 1992
                          The Cove Software Group
                            All Rights Reserved

    The copyright owner hereby licenses you to: use the software except
    as below; make as many copies of the program and documentation as
    you wish; give such copies to anyone; and distribute the software
    and documentation via electronic means.  There is no charge for any
    of the above.

    You are specifically prohibited from charging, or requesting
    donations, for any such copies, however made; and from distributing
    the software and/or documentation with commercial products without
    prior permission in writing from the copyright owner.

    Persons and organizations who are engaged in the distribution of
    shareware, "freeware", and/or public domain software may include RTMEM
    on distribution disks as long as charges are made on a per-disk
    basis rather than a per-program basis.  The charge per disk may not
    exceed $7 US.  Such persons and organizations must not represent
    themselves as vendors, distributors, or sellers of RTMEM.

    RTMEM may not be used in a commercial, governmental, or institutional
    environment.  It is intended for personal use only.  Other users
    should contact us for licensing information.

    No copy of the software may be distributed without this document;
    and the contents of the document must not be altered.

    There is no warranty of any kind, and the copyright owner is not
    liable for damages of any kind.  By using this free software, you
    agree to this.

                      -------------------------------

                          The Cove Software Group
                            Post Office Box 1072
                            Columbia, MD  21044
                                410/992-9371
                           CompuServe: 76703,2002

                     Program and documentation author:
                           Christoper J. Dunford

         ----------------end-of-author's-documentation---------------

                         Software Library Information:

                    This disk copy provided as a service of

                           Public (software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  PsL cannot debug pro-
         programs over the telephone, though we can answer questions.

         Disks in the PsL are updated  monthly,  so if you did not get
         this disk directly from the PsL, you should be aware that the
         files in this set may no longer be the current versions. Also,
         if you got this disk from another vendor and are having prob-
         lems,  be aware that  some files may have become corrupted or
         lost by that vendor. Get a current, working disk from PsL.

         For a copy of the latest monthly software library newsletter
         and a list of the 4,000+ disks in the library, call or write

                           Public (software) Library
                               P.O.Box 35705 - F
                            Houston, TX 77235-5705

                                 Orders only:
                                1-800-2424-PSL
                              MC/Visa/AmEx/Discover

                          Outside of U.S. or in Texas
                          or for general information,
                              Call 1-713-524-6394